/*
 *    Copyright (c) 2018-2025, lengleng All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * Redistributions of source code must retain the above copyright notice,
 * this list of conditions and the following disclaimer.
 * Redistributions in binary form must reproduce the above copyright
 * notice, this list of conditions and the following disclaimer in the
 * documentation and/or other materials provided with the distribution.
 * Neither the name of the pig4cloud.com developer nor the names of its
 * contributors may be used to endorse or promote products derived from
 * this software without specific prior written permission.
 * Author: lengleng (wangiegie@gmail.com)
 */

package com.pig4cloud.pig.admin.api.feign;

import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.pig4cloud.pig.common.core.constant.ServiceNameConstants;
import com.pig4cloud.pig.common.core.util.R;
import com.pig4cloud.pig.common.feign.annotation.NoToken;
import org.springframework.cloud.openfeign.FeignClient;
import org.springframework.web.bind.annotation.*;

import java.util.Map;

/**
 * 远程令牌服务接口
 * <p>
 * 通过Feign客户端调用认证服务的令牌管理功能，提供OAuth2令牌的查询、删除等操作。
 * 主要用于管理系统中的访问令牌，实现用户会话管理和强制下线等功能
 * </p>
 *
 * @author lengleng
 * @date 2025/05/30
 */
@FeignClient(contextId = "remoteTokenService", value = ServiceNameConstants.AUTH_SERVICE)
public interface RemoteTokenService {

	/**
	 * 分页查询令牌信息
	 * <p>
	 * 获取系统中所有活跃的OAuth2令牌信息，支持分页查询。
	 * 使用@NoToken注解表示该接口为内部服务调用，不需要认证
	 * </p>
	 * 
	 * @param params 分页查询参数，包含current（当前页）、size（每页大小）等
	 * @return 包含令牌分页信息的响应结果
	 */
	@NoToken
	@PostMapping("/token/page")
	R<Page> getTokenPage(@RequestBody Map<String, Object> params);

	/**
	 * 删除指定令牌
	 * <p>
	 * 根据令牌值删除对应的OAuth2令牌，用于强制用户下线或清理过期令牌。
	 * 删除后用户需要重新登录获取新令牌
	 * </p>
	 * 
	 * @param token 要删除的令牌值
	 * @return 删除操作结果，成功返回true，失败返回false
	 */
	@NoToken
	@DeleteMapping("/token/remove/{token}")
	R<Boolean> removeTokenById(@PathVariable("token") String token);

	/**
	 * 查询令牌详细信息
	 * <p>
	 * 根据令牌值查询对应的用户信息和令牌元数据，包括用户名、权限、过期时间等。
	 * 主要用于令牌验证和用户信息获取
	 * </p>
	 * 
	 * @param token 用户令牌值
	 * @return 包含用户信息和令牌元数据的Map对象
	 */
	@NoToken
	@GetMapping("/token/query-token")
	R<Map<String, Object>> queryToken(@RequestParam("token") String token);

}
